home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_apache2.idb / usr / freeware / apache2 / include / util_ldap.h.z / util_ldap.h
C/C++ Source or Header  |  2002-07-08  |  13KB  |  290 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54.  
  55. #ifndef UTIL_LDAP_H
  56. #define UTIL_LDAP_H
  57.  
  58. #include <apr_ldap.h>
  59.  
  60. /* this whole thing disappears if LDAP is not enabled */
  61. #ifdef APU_HAS_LDAP
  62.  
  63. /* APR header files */
  64. #include <apr_thread_mutex.h>
  65. #include <apr_thread_rwlock.h>
  66. #include <apr_tables.h>
  67. #include <apr_time.h>
  68.  
  69. /* Apache header files */
  70. #include "ap_config.h"
  71. #include "httpd.h"
  72. #include "http_config.h"
  73. #include "http_core.h"
  74. #include "http_log.h"
  75. #include "http_protocol.h"
  76. #include "http_request.h"
  77.  
  78.  
  79. /*
  80.  * LDAP Connections
  81.  */
  82.  
  83. /* Values that the deref member can have */
  84. typedef enum {
  85.     never=LDAP_DEREF_NEVER, 
  86.     searching=LDAP_DEREF_SEARCHING, 
  87.     finding=LDAP_DEREF_FINDING, 
  88.     always=LDAP_DEREF_ALWAYS
  89. } deref_options;
  90.  
  91. /* Structure representing an LDAP connection */
  92. typedef struct util_ldap_connection_t {
  93.     LDAP *ldap;
  94.     apr_pool_t *pool;            /* Pool from which this connection is created */
  95.     apr_thread_mutex_t *lock;            /* Lock to indicate this connection is in use */
  96.     int bound;                /* Flag to indicate whether this connection is bound yet */
  97.  
  98.     const char *host;                /* Name of the LDAP server (or space separated list) */
  99.     int port;                /* Port of the LDAP server */
  100.     deref_options deref;        /* how to handle alias dereferening */
  101.  
  102.     const char *binddn;                    /* DN to bind to server (can be NULL) */
  103.     const char *bindpw;                    /* Password to bind to server (can be NULL) */
  104.  
  105.     int netscapessl;            /* True if use Netscape SSL connection */
  106.     const char *certtdb;            /* Path to Netscape CA database */
  107.  
  108.     int starttls;                     /* True if StartTLS is enabled */
  109.     int withtls;            /* True if StartTLS on this connection */
  110.  
  111.     const char *reason;            /* Reason for an error failure */
  112.  
  113.     struct util_ldap_connection_t *next;
  114. } util_ldap_connection_t;
  115.  
  116. /* LDAP cache state information */ 
  117. typedef struct util_ldap_state_t {
  118.     apr_pool_t *pool;        /* pool from which this state is allocated */
  119.     apr_thread_mutex_t *mutex;        /* mutex lock for the connection list */
  120.  
  121.     apr_size_t cache_bytes;    /* Size (in bytes) of shared memory cache */
  122.     long search_cache_ttl;    /* TTL for search cache */
  123.     long search_cache_size;    /* Size (in entries) of search cache */
  124.     long compare_cache_ttl;    /* TTL for compare cache */
  125.     long compare_cache_size;    /* Size (in entries) of compare cache */
  126.  
  127.     struct util_ldap_connection_t *connections;
  128. #ifdef APU_HAS_LDAP_NETSCAPE_SSL
  129.     int have_certdb;
  130. #endif
  131. } util_ldap_state_t;
  132.  
  133.  
  134. /**
  135.  * Open a connection to an LDAP server
  136.  * @param ldc A structure containing the expanded details of the server
  137.  *            to connect to. The handle to the LDAP connection is returned
  138.  *            as ldc->ldap.
  139.  * @tip This function connects to the LDAP server and binds. It does not
  140.  *      connect if already connected (ldc->ldap != NULL). Does not bind
  141.  *      if already bound.
  142.  * @return If successful LDAP_SUCCESS is returned.
  143.  * @deffunc int util_ldap_connection_open(util_ldap_connection_t *ldc)
  144.  */
  145. int util_ldap_connection_open(util_ldap_connection_t *ldc);
  146.  
  147. /**
  148.  * Close a connection to an LDAP server
  149.  * @param ldc A structure containing the expanded details of the server
  150.  *            that was connected.
  151.  * @tip This function unbinds from the LDAP server, and clears ldc->ldap.
  152.  *      It is possible to rebind to this server again using the same ldc
  153.  *      structure, using apr_ldap_open_connection().
  154.  * @deffunc util_ldap_close_connection(util_ldap_connection_t *ldc)
  155.  */
  156. void util_ldap_connection_close(util_ldap_connection_t *ldc);
  157.  
  158. /**
  159.  * Destroy a connection to an LDAP server
  160.  * @param ldc A structure containing the expanded details of the server
  161.  *            that was connected.
  162.  * @tip This function is registered with the pool cleanup to close down the
  163.  *      LDAP connections when the server is finished with them.
  164.  * @deffunc apr_status_t util_ldap_connection_destroy(util_ldap_connection_t *ldc)
  165.  */
  166. apr_status_t util_ldap_connection_destroy(void *param);
  167.  
  168. /**
  169.  * Find a connection in a list of connections
  170.  * @param r The request record
  171.  * @param host The hostname to connect to (multiple hosts space separated)
  172.  * @param port The port to connect to
  173.  * @param binddn The DN to bind with
  174.  * @param bindpw The password to bind with
  175.  * @param deref The dereferencing behavior
  176.  * @param netscapessl Start SSL on the connection using ldapssl_client_init() [0|1]
  177.  * @param starttls Start TLS using STARTTLS parameter [0|1]
  178.  * @tip Once a connection is found and returned, a lock will be acquired to
  179.  *      lock that particular connection, so that another thread does not try and
  180.  *      use this connection while it is busy. Once you are finished with a connection,
  181.  *      apr_ldap_connection_close() must be called to release this connection.
  182.  * @deffunc util_ldap_connection_t *util_ldap_connection_find(request_rec *r, const char *host, int port,
  183.  *                                                           const char *binddn, const char *bindpw, deref_options deref,
  184.  *                                                           int netscapessl, int starttls)
  185.  */
  186. util_ldap_connection_t *util_ldap_connection_find(request_rec *r, const char *host, int port,
  187.                                                   const char *binddn, const char *bindpw, deref_options deref,
  188.                                                   int netscapessl, int starttls);
  189.  
  190.  
  191. /**
  192.  * Compare two DNs for sameness
  193.  * @param r The request record
  194.  * @param ldc The LDAP connection being used.
  195.  * @param url The URL of the LDAP connection - used for deciding which cache to use.
  196.  * @param dn The first DN to compare.
  197.  * @param reqdn The DN to compare the first DN to.
  198.  * @param compare_dn_on_server Flag to determine whether the DNs should be checked using
  199.  *                             LDAP calls or with a direct string comparision. A direct
  200.  *                             string comparison is faster, but not as accurate - false
  201.  *                             negative comparisons are possible.
  202.  * @tip Two DNs can be equal and still fail a string comparison. Eg "dc=example,dc=com"
  203.  *      and "dc=example, dc=com". Use the compare_dn_on_server unless there are serious
  204.  *      performance issues.
  205.  * @deffunc int util_ldap_cache_comparedn(request_rec *r, util_ldap_connection_t *ldc,
  206.  *                                        const char *url, const char *dn, const char *reqdn,
  207.  *                                        int compare_dn_on_server)
  208.  */
  209. int util_ldap_cache_comparedn(request_rec *r, util_ldap_connection_t *ldc, 
  210.                               const char *url, const char *dn, const char *reqdn, 
  211.                               int compare_dn_on_server);
  212.  
  213. /**
  214.  * A generic LDAP compare function
  215.  * @param r The request record
  216.  * @param ldc The LDAP connection being used.
  217.  * @param url The URL of the LDAP connection - used for deciding which cache to use.
  218.  * @param dn The DN of the object in which we do the compare.
  219.  * @param attrib The attribute within the object we are comparing for.
  220.  * @param value The value of the attribute we are trying to compare for. 
  221.  * @tip Use this function to determine whether an attribute/value pair exists within an
  222.  *      object. Typically this would be used to determine LDAP group membership.
  223.  * @deffunc int util_ldap_cache_compare(request_rec *r, util_ldap_connection_t *ldc,
  224.  *                                      const char *url, const char *dn, const char *attrib, const char *value)
  225.  */
  226. int util_ldap_cache_compare(request_rec *r, util_ldap_connection_t *ldc,
  227.                             const char *url, const char *dn, const char *attrib, const char *value);
  228.  
  229. /**
  230.  * Checks a username/password combination by binding to the LDAP server
  231.  * @param r The request record
  232.  * @param ldc The LDAP connection being used.
  233.  * @param url The URL of the LDAP connection - used for deciding which cache to use.
  234.  * @param basedn The Base DN to search for the user in.
  235.  * @param scope LDAP scope of the search.
  236.  * @param attrs LDAP attributes to return in search.
  237.  * @param filter The user to search for in the form of an LDAP filter. This filter must return
  238.  *               exactly one user for the check to be successful.
  239.  * @param bindpw The user password to bind as.
  240.  * @param binddn The DN of the user will be returned in this variable.
  241.  * @param retvals The values corresponding to the attributes requested in the attrs array.
  242.  * @tip The filter supplied will be searched for. If a single entry is returned, an attempt
  243.  *      is made to bind as that user. If this bind succeeds, the user is not validated.
  244.  * @deffunc int util_ldap_cache_checkuserid(request_rec *r, util_ldap_connection_t *ldc,
  245.  *                                          char *url, const char *basedn, int scope, char **attrs,
  246.  *                                          char *filter, char *bindpw, char **binddn, char ***retvals)
  247.  */
  248. int util_ldap_cache_checkuserid(request_rec *r, util_ldap_connection_t *ldc,
  249.                               const char *url, const char *basedn, int scope, char **attrs,
  250.                               const char *filter, const char *bindpw, const char **binddn, const char ***retvals);
  251.  
  252. /* from apr_ldap_cache.c */
  253.  
  254. /**
  255.  * Init the LDAP cache
  256.  * @param pool The pool to use to initialise the cache
  257.  * @param reqsize The size of the shared memory segement to request. A size
  258.  *                of zero requests the max size possible from
  259.  *                apr_shmem_init()
  260.  * @deffunc void util_ldap_cache_init(apr_pool_t *p)
  261.  * @return The status code returned is the status code of the
  262.  *         apr_smmem_init() call. Regardless of the status, the cache
  263.  *         will be set up at least for in-process or in-thread operation.
  264.  */
  265. apr_status_t util_ldap_cache_init(apr_pool_t *pool, apr_size_t reqsize);
  266.  
  267. /**
  268.  * Display formatted stats for cache
  269.  * @param The pool to allocate the returned string from
  270.  * @tip This function returns a string allocated from the provided pool that describes
  271.  *      various stats about the cache.
  272.  * @deffunc char *util_ald_cache_display(apr_pool_t *pool)
  273.  */
  274. char *util_ald_cache_display(apr_pool_t *pool);
  275.  
  276.  
  277. /* from apr_ldap_cache_mgr.c */
  278.  
  279. /**
  280.  * Display formatted stats for cache
  281.  * @param The pool to allocate the returned string from
  282.  * @tip This function returns a string allocated from the provided pool that describes
  283.  *      various stats about the cache.
  284.  * @deffunc char *util_ald_cache_display(apr_pool_t *pool)
  285.  */
  286. char *util_ald_cache_display(apr_pool_t *pool);
  287.  
  288. #endif /* APU_HAS_LDAP */
  289. #endif /* UTIL_LDAP_H */
  290.